home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / malloc.z / malloc
Encoding:
Text File  |  2002-10-03  |  7.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. MMMMAAAALLLLLLLLOOOOCCCC((((3333CCCC))))                                                          MMMMAAAALLLLLLLLOOOOCCCC((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      malloc, free, realloc, calloc, memalign, valloc - main memory allocator
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddlllliiiibbbb....hhhh>>>>
  13.  
  14.      vvvvooooiiiidddd ****mmmmaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  15.  
  16.      vvvvooooiiiidddd ffffrrrreeeeeeee ((((vvvvooooiiiidddd ****ppppttttrrrr))));;;;
  17.  
  18.      vvvvooooiiiidddd ****rrrreeeeaaaalllllllloooocccc ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  19.  
  20.      vvvvooooiiiidddd ****ccccaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt nnnneeeelllleeeemmmm,,,, ssssiiiizzzzeeee____tttt eeeellllssssiiiizzzzeeee))));;;;
  21.  
  22.      vvvvooooiiiidddd ****mmmmeeeemmmmaaaalllliiiiggggnnnn ((((ssssiiiizzzzeeee____tttt aaaalllliiiiggggnnnnmmmmeeeennnntttt,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  23.  
  24.      vvvvooooiiiidddd ****vvvvaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  25.  
  26. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  27.      mmmmaaaalllllllloooocccc and ffffrrrreeeeeeee provide a simple general-purpose memory allocation
  28.      package.  mmmmaaaalllllllloooocccc returns a pointer to a block of at least _s_i_z_e bytes
  29.      suitably aligned for any use.
  30.  
  31.      The argument to ffffrrrreeeeeeee is a pointer to a block previously allocated by
  32.      mmmmaaaalllllllloooocccc; after ffffrrrreeeeeeee is performed this space is made available for further
  33.      allocation, but its contents are left undisturbed.
  34.  
  35.      Undefined results will occur if the space allocated by mmmmaaaalllllllloooocccc is overrun
  36.      or if some random value is passed as the argument to ffffrrrreeeeeeee.
  37.  
  38.      mmmmaaaalllllllloooocccc allocates the first big enough contiguous reach of free space
  39.      found in a circular search from the last block allocated or freed,
  40.      coalescing adjacent free blocks as it searches.  It calls ssssbbbbrrrrkkkk [see
  41.      _bbbb_rrrr_kkkk(2)] to get more memory from the system when there is no suitable
  42.      space already free.
  43.  
  44.      rrrreeeeaaaalllllllloooocccc changes the size of the block pointed to by _p_t_r to _s_i_z_e bytes and
  45.      returns a pointer to the (possibly moved) block.  The contents will be
  46.      unchanged up to the lesser of the new and old sizes.  If no free block of
  47.      _s_i_z_e bytes is available in the storage arena, then rrrreeeeaaaalllllllloooocccc will ask
  48.      mmmmaaaalllllllloooocccc to enlarge the arena by _s_i_z_e bytes and will then move the data to
  49.      the new space.  If _p_t_r is NULL, rrrreeeeaaaalllllllloooocccc behaves like _mmmm_aaaa_llll_llll_oooo_cccc(_s_i_z_e).  If
  50.      _s_i_z_e is zero, the storage associated with _p_t_r is freed and rrrreeeeaaaalllllllloooocccc
  51.      returns the same result as does mmmmaaaalllllllloooocccc(0).
  52.  
  53.      ccccaaaalllllllloooocccc allocates space for an array of _n_e_l_e_m elements of size _e_l_s_i_z_e.
  54.      The space is initialized to zeros.
  55.  
  56.      mmmmeeeemmmmaaaalllliiiiggggnnnn allocates _s_i_z_e bytes on a specified alignment boundary and
  57.      returns a pointer to the allocated block.  The value of the returned
  58.      address is guaranteed to be a multiple of _a_l_i_g_n_m_e_n_t.  Note that the value
  59.      of _a_l_i_g_n_m_e_n_t must be a power of two and must be greater than or equal to
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MMMMAAAALLLLLLLLOOOOCCCC((((3333CCCC))))                                                          MMMMAAAALLLLLLLLOOOOCCCC((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      the size of a word, or, for 64 bit objects, the size of a doubleword.
  75.  
  76.      _vvvv_aaaa_llll_llll_oooo_cccc(_s_i_z_e) is equivalent to _mmmm_eeee_mmmm_aaaa_llll_iiii_gggg_nnnn(_ssss_yyyy_ssss_cccc_oooo_nnnn_ffff(______SSSS_CCCC______PPPP_AAAA_GGGG_EEEE_SSSS_IIII_ZZZZ_EEEE),_s_i_z_e). For
  77.      more information see _ssss_yyyy_ssss_cccc_oooo_nnnn_ffff(3c).
  78.  
  79.      Each of the allocation routines returns a pointer to space suitably
  80.      aligned (after possible pointer coercion) for storage of any type of
  81.      object.
  82.  
  83. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  84.      brk(2), sysconf(3c), malloc(3X)
  85.  
  86. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  87.      mmmmaaaalllllllloooocccc, rrrreeeeaaaalllllllloooocccc,,,, ccccaaaalllllllloooocccc,,,, mmmmeeeemmmmaaaalllliiiiggggnnnn,,,, and vvvvaaaalllllllloooocccc return a NULL pointer if
  88.      there is no available memory or if the arena has been detectably
  89.      corrupted by storing outside the bounds of a block.  When this happens
  90.      the block pointed to by _p_t_r may be destroyed.
  91.  
  92. NNNNOOOOTTTTEEEESSSS
  93.      How an application manages its heap can greatly affect the performance of
  94.      these routines. For most applications, this set will perform well.  For
  95.      some applications, the more flexible _mmmm_aaaa_llll_llll_oooo_cccc(3X) package might be more
  96.      appropriate.
  97.  
  98.      A SEGV or Bus Error inside the mmmmaaaalllllllloooocccc routine is almost certainly caused
  99.      by a previous memory overwrite by the user. This is a delayed error which
  100.      is caused by a previous overwrite of unallocated memory and is not a bug
  101.      in mmmmaaaalllllllloooocccc itself.
  102.  
  103.      When called with _s_i_z_e of zero, mmmmaaaalllllllloooocccc returns a valid pointer to a block
  104.      of zero bytes.  Storage into a block of length zero will corrupt the
  105.      mmmmaaaalllllllloooocccc arena and may have serious consequences.
  106.  
  107.      Products, libraries, or commands that provide their own mmmmaaaalllllllloooocccc package
  108.      must provide all of the entry points listed above, or the normal _llll_iiii_bbbb_cccc
  109.      _mmmm_aaaa_llll_llll_oooo_cccc entry point for the unimplemented routine(s) may be called
  110.      instead, leading to corrupted heaps, since it is unlikely that the
  111.      internal details of the heap management will be the same.  If the mmmmaaaalllllllloooocccc
  112.      package is also intended to replace mmmmaaaalllllllloooocccc(3X), it must also provide the
  113.      additional routines listed there.
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.